<!DOCTYPE HTML PUBLIC "-//ORA//DTD CD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>[Chapter 16] jdb</TITLE>
<META NAME="author" CONTENT="David Flanagan">
<META NAME="date" CONTENT="Thu Jul 31 16:04:28 1997">
<META NAME="form" CONTENT="html">
<META NAME="metadata" CONTENT="dublincore.0.1">
<META NAME="objecttype" CONTENT="book part">
<META NAME="otheragent" CONTENT="gmat dbtohtml">
<META NAME="publisher" CONTENT="O'Reilly &amp; Associates, Inc.">
<META NAME="source" CONTENT="SGML">
<META NAME="subject" CONTENT="Java">
<META NAME="title" CONTENT="Java in a Nutshell">
<META HTTP-EQUIV="Content-Script-Type" CONTENT="text/javascript">
</HEAD>
<body vlink="#551a8b" alink="#ff0000" text="#000000" bgcolor="#FFFFFF" link="#0000ee">

<DIV CLASS=htmlnav>
<H1><a href='index.htm'><IMG SRC="gifs/smbanner.gif"
     ALT="Java in a Nutshell" border=0></a></H1>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch16_08.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><B><FONT FACE="ARIEL,HELVETICA,HELV,SANSERIF" SIZE="-1">Chapter 16<br>JDK Tools</FONT></B></TD>
<td width=172 align=right valign=top><A HREF="ch16_10.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
</table>

&nbsp;
<hr align=left width=515>
</DIV>
<A NAME="CH16.JDB.JAVA.DE1"></A>

<DIV CLASS=refnamediv>
<H1>jdb</H1>

<H2>Name</H2>

jdb---The Java Debugger

</DIV>

<DIV CLASS=refsect1>
<h2 CLASS=refsect1><A CLASS="TITLE" NAME="JNUT2-CH-16-SECT-9.1">Availability</A></h2>

<P CLASS=para>
JDK 1.0 and later.

</DIV>

<DIV CLASS=refsect1>
<h2 CLASS=refsect1><A CLASS="TITLE" NAME="JNUT2-CH-16-SECT-9.2">Synopsis</A></h2>

<DIV CLASS=screen>
<P>
<PRE>
jdb [ <I CLASS=emphasis>java options</I> ] <I CLASS=emphasis>class</I>
jdb [ -host <I CLASS=emphasis>hostname</I> ] -password <I CLASS=emphasis>password</I>
</PRE>
</DIV>

</DIV>

<DIV CLASS=refsect1>
<h2 CLASS=refsect1><A CLASS="TITLE" NAME="JNUT2-CH-16-SECT-9.3">Description</A></h2>

<P CLASS=para>
<I CLASS=emphasis>jdb</I> is a debugger for Java classes.  It is
text-based, command-line oriented, and has a command syntax
like that of the UNIX <I CLASS=emphasis>dbx</I> or <I CLASS=emphasis>gdb</I> debuggers.

<P CLASS=para>
When <I CLASS=emphasis>jdb</I> is invoked with the name of a Java class, it
starts another copy of the <I CLASS=emphasis>java</I> interpreter, passing
any specified <I CLASS=emphasis>java</I> options to the interpreter. <I CLASS=emphasis>jdb</I>
is itself a Java program, running in its own
copy of the interpreter. This new interpreter loads the
specified class file and stops for debugging before
executing the first Java byte-code.

<P CLASS=para>
<I CLASS=emphasis>jdb</I> may also be started with the <tt CLASS=literal>-password</tt> and
optional <tt CLASS=literal>-host</tt> arguments.  Invoked in this way,
<I CLASS=emphasis>jdb</I> "attaches itself" to an already running copy of
the interpreter.  In order for this to work, the Java
interpreter running the program to be debugged must have
been started with the <tt CLASS=literal>-debug</tt> option.  When the
interpreter is started with this option, it prints a
password that must be used with the <I CLASS=emphasis>jdb</I>
<tt CLASS=literal>-password</tt> option.

<P CLASS=para>
Once a debugging session is started, you may issue any of
the commands described below.

</DIV>

<DIV CLASS=refsect1>
<h2 CLASS=refsect1><A CLASS="TITLE" NAME="JNUT2-CH-16-SECT-9.4">Options</A></h2>

<P CLASS=para>
When invoking <I CLASS=emphasis>jdb</I> with a specified class file, any of
the <I CLASS=emphasis>java</I> interpreter options may be specified.  See
the <I CLASS=emphasis>java</I> reference page for an explanation of these
options.

<P CLASS=para>
When attaching <I CLASS=emphasis>jdb</I> to an already running Java
interpreter, the following options are available:

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><tt CLASS=literal>-host</tt> <I CLASS=emphasis>hostname</I><br>
<DD>

<P CLASS=para>
Specifies the name of the host upon which the desired
interpreter session is running.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>-password</tt> <I CLASS=emphasis>password</I><br>
<DD>

<P CLASS=para>
This option is required to attach to a running interpreter.
The interpreter must have been started with the
<tt CLASS=literal>-debug</tt> option, and this <tt CLASS=literal>-password</tt> option
specifies the password that the interpreter generated.  Only
a debugger that knows this password is allowed to
attach to the interpreter.  Note that the passwords
generated by <I CLASS=emphasis>java</I> should not be considered
cryptologically secure.</DL>
</DIV>

<DIV CLASS=refsect1>
<h2 CLASS=refsect1><A CLASS="TITLE" NAME="JNUT2-CH-16-SECT-9.5">Commands</A></h2>

<P CLASS=para>
<I CLASS=emphasis>jdb</I> understands the following debugging commands:

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><tt CLASS=literal>!!</tt><br>
<DD>

<P CLASS=para>
This is a shorthand command that is replaced with the text
of the last command entered.  It may be followed with
additional text that is appended to that previous command.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>catch</tt> [ <I CLASS=emphasis>exception class</I> ]<br>
<DD>

<P CLASS=para>
Cause a breakpoint whenever the specified exception is
thrown.  If no exception is specified, the command lists the exceptions
currently being caught.  Use <tt CLASS=literal>ignore</tt> to stop these
breakpoints from occurring.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>classes</tt><br>
<DD>

<P CLASS=para>
List all classes that have been loaded.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>clear</tt> [ <I CLASS=emphasis>class</I>:<I CLASS=emphasis>line</I> ]<br>
<DD>

<P CLASS=para>
Remove the breakpoint set at the specified line of the
specified class.  Typing <tt CLASS=literal>clear</tt> or <tt CLASS=literal>stop</tt> with
no arguments displays a list of current breakpoints and the
line numbers that they are set at.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>cont</tt><br>
<DD>

<P CLASS=para>
Resume execution.  This command should be used when the current
thread is stopped at a breakpoint.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>down</tt> [ <I CLASS=emphasis>n</I> ]<br>
<DD>

<P CLASS=para>
Move down <tt CLASS=literal>n</tt> frames in the call stack of the current
thread.  If <tt CLASS=literal>n</tt> is not specified, move down one frame.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>dump </tt><I CLASS=emphasis>id(s)</I><br>
<DD>

<P CLASS=para>
Print the value of all fields of the specified object or
objects.  If you specify the name of a class, <tt CLASS=literal>dump</tt>
displays all class (static) methods and variables of the
class, and also displays the superclass and list of
implemented interfaces.  Objects and classes may be
specified by name or by their eight-digit hexadecimal ID
number.  Threads may also be specified with the shorthand
<tt CLASS=literal>t@</tt><I CLASS=emphasis>thread-number</I>. 

<p>
<DT CLASS=varlistentry><tt CLASS=literal>exit (or quit)</tt><br>
<DD>

<P CLASS=para>
Quit <I CLASS=emphasis>jdb</I>.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>gc</tt><br>
<DD>

<P CLASS=para>
Run the garbage collector to force unused objects to be reclaimed.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>help (or ?)</tt><br>
<DD>

<P CLASS=para>
Display a list of all <I CLASS=emphasis>jdb</I> commands.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>ignore</tt> <I CLASS=emphasis>exception class</I><br>
<DD>

<P CLASS=para>
Do not treat the specified exception as a breakpoint.
This command turns off a <tt CLASS=literal>catch</tt> command.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>list</tt> [ <I CLASS=emphasis>line number</I> ]<br>
<DD>

<P CLASS=para>
List the specified line of source code as well as several
lines that appear before and after it.  If no line number is
specified, use the line number of the current stack frame of
the current thread.  The lines listed are from the source
file of the current stack frame of the current thread.  Use
the <tt CLASS=literal>use</tt> command to tell <I CLASS=emphasis>jdb</I> where to find
source files.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>load</tt> <I CLASS=emphasis>classname</I><br>
<DD>

<P CLASS=para>
Load the specified class into <I CLASS=emphasis>jdb</I>.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>locals</tt><br>
<DD>

<P CLASS=para>
Display a list of local variables for the current stack
frame.  Java code must be compiled with the <tt CLASS=literal>-g</tt>
option in order to contain local variable information.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>memory</tt><br>
<DD>

<P CLASS=para>
Display a summary of memory usage for the Java program being
debugged.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>methods</tt> <I CLASS=emphasis>class</I><br>
<DD>

<P CLASS=para>
List all methods of the specified class.  Use <tt CLASS=literal>dump</tt>
to list the instance variables or an object or the class
(static) variables of a class.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>print</tt> <I CLASS=emphasis>id(s)</I><br>
<DD>

<P CLASS=para>
Print the value of the specified item or items.  Each item
may be a class, object, field, or local variable, and may be
specified by name or by eight-digit hexadecimal ID number.
You may also refer to threads with the special syntax
<tt CLASS=literal>t@</tt><I CLASS=emphasis>thread-number</I>.  The <tt CLASS=literal>print</tt> command displays an object's value by invoking its
<tt CLASS=literal>toString()</tt> method.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>resume</tt> [ <I CLASS=emphasis>thread(s)</I> ]<br>
<DD>

<P CLASS=para>
Resume execution of the specified thread or threads.  If no
threads are specified, all suspended threads are resumed.
See also <tt CLASS=literal>suspend</tt>.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>run</tt> [ <I CLASS=emphasis>class</I> ] [ <I CLASS=emphasis>args</I> ]<br>
<DD>

<P CLASS=para>
Run the <tt CLASS=literal>main()</tt> method of the specified class,
passing the specified arguments to it.  If no class or
arguments are specified, use the class and arguments
specified on the <I CLASS=emphasis>jdb</I> command line.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>step</tt><br>
<DD>

<P CLASS=para>
Run the current line of the current thread and stop again.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>stop [ at</tt> <I CLASS=emphasis>class</I>:<I CLASS=emphasis>line</I> ]<br><tt CLASS=literal>stop [ in</tt> <I CLASS=emphasis>class</I>.<I CLASS=emphasis>method</I> ]<br>
<DD>

<P CLASS=para>
Set a breakpoint at the specified line of the specified
class or at the beginning of the specified method of the
specified class.  Program execution stops when it
reaches this line or enters the method.  If <tt CLASS=literal>stop</tt> is
executed with no arguments, then it lists the current
breakpoints.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>suspend</tt> [ <I CLASS=emphasis>thread(s)</I> ]<br>
<DD>

<P CLASS=para>
Suspend the specified thread or threads.  If no threads are
specified, suspend all running threads.  Use <tt CLASS=literal>resume</tt>
to restart them.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>thread</tt> <I CLASS=emphasis>thread</I><br>
<DD>

<P CLASS=para>
Set the current thread to the specified thread.  This thread
is used implicitly by a number of other <I CLASS=emphasis>jdb</I>
commands.  The thread may be specified by name or number.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>threadgroup</tt> <I CLASS=emphasis>name</I><br>
<DD>

<P CLASS=para>
Set the current thread group to the named thread group.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>threadgroups</tt><br>
<DD>

<P CLASS=para>
List all thread groups running in the Java interpreter
session being debugged.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>threads</tt> [ <I CLASS=emphasis>threadgroups</I> ]<br>
<DD>

<P CLASS=para>
List all threads in the named thread group.  If no
thread group is specified, list all threads in the current
thread group (specified by <tt CLASS=literal>threadgroup</tt>).

<p>
<DT CLASS=varlistentry><tt CLASS=literal>up</tt> [ <I CLASS=emphasis>n</I> ]<br>
<DD>

<P CLASS=para>
Move up <tt CLASS=literal>n</tt> frames in the call stack of the current
thread.  If <tt CLASS=literal>n</tt> is not specified, move up one frame.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>use</tt> [ <I CLASS=emphasis>source-file-path</I> ]<br>
<DD>

<P CLASS=para>
Set the path used by <I CLASS=emphasis>jdb</I> to look up source files for
the classes being debugged.  If no path is specified,
display the current source path being used.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>where [</tt> <I CLASS=emphasis>thread</I> <tt CLASS=literal>] [ all ]</tt><br>
<DD>

<P CLASS=para>
Display a stack trace for the specified thread.  If no
thread is specified, display a stack trace for the current
thread.  If <tt CLASS=literal>all</tt> is specified, display a stack trace
for all threads.</DL>
</DIV>

<DIV CLASS=refsect1>
<h2 CLASS=refsect1><A CLASS="TITLE" NAME="JNUT2-CH-16-SECT-9.6">Environment</A></h2>

<DL CLASS=variablelist>
<DT CLASS=varlistentry><tt CLASS=literal>CLASSPATH</tt><br>
<DD>

<P CLASS=para>
Specifies an ordered list (colon-separated on UNIX,
semicolon-separated on Windows systems) of directories and
ZIP files in which <I CLASS=emphasis>jdb</I> should look for class
definitions.  When a path is specified with this environment
variable, <I CLASS=emphasis>jdb</I> always implicitly appends the location of
the system classes to the end of the path.  If this
environment variable is not specified, the default path
is the current directory and the system classes.  This
variable is overridden by the <tt CLASS=literal>-classpath</tt> option.</DL>
</DIV>

<DIV CLASS=refsect1>
<h2 CLASS=refsect1><A CLASS="TITLE" NAME="JNUT2-CH-16-SECT-9.7">See Also</A></h2>

<P CLASS=para>
<I CLASS=emphasis>java</I>

</DIV>


<DIV CLASS=htmlnav>

<P>
<HR align=left width=515>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch16_08.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><a href="index.htm"><img src='gifs/txthome.gif' border=0 alt='Home'></a></td>
<td width=172 align=right valign=top><A HREF="ch16_10.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
<tr>
<td width=172 align=left valign=top>javap</td>
<td width=171 align=center valign=top><a href="index/idx_0.htm"><img src='gifs/index.gif' alt='Book Index' border=0></a></td>
<td width=172 align=right valign=top>native2ascii</td>
</tr>
</table>
<hr align=left width=515>

<IMG SRC="gifs/smnavbar.gif" USEMAP="#map" BORDER=0> 
<MAP NAME="map"> 
<AREA SHAPE=RECT COORDS="0,0,108,15" HREF="../javanut/index.htm"
alt="Java in a Nutshell"> 
<AREA SHAPE=RECT COORDS="109,0,200,15" HREF="../langref/index.htm" 
alt="Java Language Reference"> 
<AREA SHAPE=RECT COORDS="203,0,290,15" HREF="../awt/index.htm" 
alt="Java AWT"> 
<AREA SHAPE=RECT COORDS="291,0,419,15" HREF="../fclass/index.htm" 
alt="Java Fundamental Classes"> 
<AREA SHAPE=RECT COORDS="421,0,514,15" HREF="../exp/index.htm" 
alt="Exploring Java"> 
</MAP>
</DIV>

</BODY>
</HTML>
